# Cluster Name Mapping

## Background

SkyPilot allows users to assign names to clusters they launched. It is convenient, but
when the following situation happens, it can be annoying:
1. The cluster name exceeds clouds' naming length limit.
2. Multiple users in the same cloud account organization use the same cluster name.

## Solution

After #2403, SkyPilot will automatically truncate cluster names to comply with the
naming length limit of the cloud, and append a user hash to the end of the name to
distinguish clusters from different users (we make sure the final result after the append is within length limit).

## Details

There are two cluster name concepts:
- SkyPilot cluster name: This is the original "display" name users pick (or
    generated by the system) for each SkyPilot cluster. This is used in our
    CLI/API (e.g., `sky launch -c <cluster name>`).
  - `cluster_name` in code. Used in all user-facing logging.
- Cluster name on cloud: This is the auto-generated name passed to the cloud.
    We auto-process the display name above to produce this new name to ensure
    (1) distinguishing across users, in case they choose the same cluster name;
    (2) the cluster name on cloud is within length limit.
  - `cluster_name_on_cloud` in code. Used in all modules that communicated with
    the cloud provider, e.g., `ray up`, `node_provider`/`provision_lib` module, etc.
  - Recorded in the VM tag `ray-cluster-name`. (Note that the VM names include
    it as a substring, but may have additional prefixes/suffixes.)
In most cases, users need only be aware of the former.

## Examples

For a cluster name less than cloud's naming length limit, the name will only be appended
with a user hash.
```
# Original cluster name
my-cluster-name

# Cluster name on cloud
my-cluster-name-9eac
```

For a cluster name longer than cloud's naming length limit, the name will be truncated
to less than the limit, appended with a cluster name hash, and then appended with a user hash.
```
# Original cluster name
my-cluster-name-very-long

# Cluster name on cloud
my-cluster-name-3m-9eac
```
